Aminet 1 (Walnut Creek)/Aminet - June 1993 [Walnut Creek].iso/aminet/gfx/3d/isl_1_2.lzh/ISL.doc

Text File | 1993-02-10 | 6KB | 130 lines

ISL.doc - Copyright (c) 1992 John T. Grieggs, last modified 02-10-93

Current ISL version - 1.2.

ISL, the Imagine Staging Language, is a language created to make the
generation and manipulation of Imagine 2.0 staging files a whole lot
easier.  If you have ever used the Action editor in earnest, you know
that certain types of operations are easy (such as adding a single
light) while others are not (such as adding more frames and causing
your existing objects to appear in them).

ISL provides an alternative interface to the Action editor.  With ISL,
you can create your stage using the Stage and Action editors as needed,
then convert it to a fairly straightforward ASCII format, edit it as
desired using your favorite text editor, then put it back!  This is of
course the simplest way of using ISL - you could also create stages
programatically.  I have done this myself.

To use ISL productively, it is first necessary to understand a bit about
how Imagine works.  Quite a bit.  I would not attempt to use this package
if you are not comfortable with Imagine.  If you are struggling, I would
recommend that you purchase Steve Worley's excellent book on the topic,
"Understanding Imagine 2.0", read it, then come back (plug).

Back?  Good.  When you first create a Project in Imagine 2.0, Imagine
creates a staging file in your whatever.imp directory.  This staging
file, run through the ISL de-compiler destage, looks like this:

    STAGE
    MAXFRAMES 1

The command to generate this file or one like it is:

    destage binarystage asciistage

where binarystage is the Imagine staging file and asciistage is where you
want to put the ISL.

The ISL compiler will indeed eat this simple stage format.  Let's say you
just want to add some frames.  You would then have something like this:

    STAGE
    MAXFRAMES 100

The command to make this into a valid Imagine stage is:

    restage asciistage binarystage

where asciistage is your modified ISL source file and binarystage is where
you want to put the new Imagine stage.  A word of caution:  it never hurts
to make a backup copy of a staging file before stomping it!

That was too easy.  Onto ISL complexity level two.  :-)  If you bring up the
Action editor and save the stage, without touching it, it will magically
grow into something like this:

    STAGE
    MAXFRAMES 1

    CAMERA "CAMERA"
    POSITION FRAMES 1 1 XYZ 160.000000 -320.000000 160.000000
    ALIGN FRAMES 1 1 XYZ 0.000000 0.000000 0.000000
    SIZE FRAMES 1 1 XYZ 320.000000 640.000000 233.333328

    GLOBALS "GLOBALS"
    ACTOR FRAMES 1 1 BRUSH "" 0 BACKDROP "" 0 AMBIENT RGB 0.000000 0.000000
    0.000000 HORIZON RGB 0.000000 0.000000 0.000000 +ZENITH RGB 0.000000
    0.000000 0.000000 -ZENITH RGB 0.000000 0.000000 0.000000 FOG BTL
    0.000000 0.000000 0.000000 FOG RGB 0.000000 0.000000 0.000000
    STARFIELD 0.000000 TRANSITION 0 SKYBLEND 0

Note the addition of a CAMERA clause and a GLOBALS clause.  Some detail is
called for at this point.  ISL sentences generally correspond one-for-one
to Action editor entries.  There will be one line containing the name from
the far left-hand column of the Action editor entry (CAMERA "CAMERA" or
GLOBALS "GLOBALS", etc.) followed by one line for each line or line segment
in the Action editor.

So, for this simple stage, we have three clumps - the stagehdr, containing
the STAGE and MAXFRAMES clause, the CAMERA clump, containing the name clause,
a position clause, an alignment clause, and a size clause, and the globals
clump, containg the name and the actor info.

Here is an ISL object entry, showing what happens when you swap three
physical objects while changing their position and alignment:

OBJECT "PORTAL"
ACTOR FRAMES 1 40 NAME "Portal.imp/objects/Portal" CYCLE 0.000000 0.000000 TRANSITION 0
ACTOR FRAMES 41 60 NAME "Portal.imp/objects/Prtal" CYCLE 0.000000 0.000000 TRANSITION 0
ACTOR FRAMES 61 100 NAME "Portal.imp/objects/Prtl" CYCLE 0.000000 0.000000 TRANSITION 0
POSITION FRAMES 1 40 PATH "PATH" ACCEL 0 0.000000 DECEL 0 0.000000
POSITION FRAMES 41 100 XYZ 0.000000 -1000.000000 0.000000
ALIGN FRAMES 1 1 XYZ 0.000000 0.000000 0.000000
ALIGN FRAMES 2 20 XYZ 0.000000 180.000000 0.000000
ALIGN FRAMES 21 39 XYZ 0.000000 360.000000 0.000000
SIZE FRAMES 1 1 XYZ 32.000000 32.000000 32.000000

Again, we start with the object name, then follow it with one ISL line for
each Action editor line or line segment.  Note that there are two types of
POSITION line here - the first follows a path "PATH", and the second is
a tween position.  This example is from my flying Portal logo anim.

Here is another ISL object entry, showing an object with a SPFX clause:

OBJECT "EMERALD"
ACTOR FRAMES 1 12 NAME "Emerald.imp/objects/emerald2.obj" CYCLE 0.000000 0.000000 TRANSITION 0
POSITION FRAMES 1 1 XYZ 0.000000 0.000000 0.000000
ALIGN FRAMES 1 1 XYZ 0.000000 0.000000 3.750000
SIZE FRAMES 1 1 XYZ 5.000000 5.000000 6.500000
EFFECT 1 FRAMES 1 12 Rotate2.0 "Effects/Rotate2.0" ZAXIS DEGREES 45.000000

Each Special Effect has it's own syntax.  Use EFFECT 1 for SF/X 1, EFFECT 2
for SF/X 2.  The individual syntax for each effect is documented in ISL.BNF.
Note that an effect is actually recognized by the fifth word, which in this
case is Rotate2.0 - this following clause is the filename in quotes, so that
your effects can live anywhere.

I think this ought to be enough to get started using ISL.  The actual syntax
of the language is documented in the included ISL.BNF file.  The easiest way
to get started would probably be to try destage-ing, modifying, and restage-
ing your own files.  I'd stay out of ISL.BNF until you are pretty familiar
with ISL or are stuck.

Hey, wait a minute, what about frames.c?  Oh, yeah.  It's a little stage
generator I whipped up.  It's written in c, and produces a bunch of frames
ready to be averaged together (for motion blur, of course).  Take it not as
an example of sheer programming elegance, but rather as an idea of how to
programmatically generate an ISL stage.